#   │ │    this expression is fallible because at least one argument's type cannot be verified to be valid
#   │ │    '.result[0].an' argument type is 'string or undefined' and this function expected a parameter 'value' of type 'string'
#   │  update the expression to be infallible by adding a `!`: `.a = sha3!(.result[0].an)`
#   │ or change this to an infallible assignment:
#   │ .a, err = sha3(.result[0].an)

What you have here is a great step forward, but do you think we can make it even clearer with something like what I put? I still worry that the current error message will be confusing to users. I'm not sure exactly what's possible though.

If I read the above correctly you want to add two more lines:

this expression is fallible because at least one argument's type cannot be verified to be valid
// ...
update the expression to be infallible by adding a `!`: `.a = sha3!(.result[0].an)`

which should be doable and I will follow up on this.

Ultimately users should have some basic understanding about fallibility and fail safety when using VRL (which practically means adding a ! or handling the returned err).

P.S. Where users might still be confused, is with code blocks which contain fallible expressions example here. However, that part of the codebase is not easy to maintain and is need of refactoring.

#   │ │    this expression is fallible because at least one argument's type cannot be verified to be valid
#   │ │    '.result[0].an' argument type is 'string or undefined' and this function expected a parameter 'value' of type 'string'

is actually the more important update I would like to see. I think my verbiage makes it more clear exactly what the issue is: that the function is fallible because one of the arguments cannot be verified, and this is the argument (or arguments) in particular, their types, and what the function expects.

The hints on how to fix are then a cherry on top.

The hints could also include casting the arguments like:

#   │ .a = sha3(string!(.result[0].an))

I think that is closer to the "best-practice" that we want to guide people into.

Gotcha, this makes sense.